Skip to content

#9: Virtual and concrete MCP servers (concrete servers: rename and tool override) - #10

Merged
jayjfletcher merged 15 commits into
mainfrom
ring-master/2026-10-23-1917-virtual-and-concrete-mcp-servers
Oct 27, 2026
Merged

jayjfletcher merged 15 commits into
mainfrom
ring-master/2026-10-23-1917-virtual-and-concrete-mcp-servers

Conversation

@jayjfletcher

@jayjfletcher jayjfletcher commented Oct 25, 2026 •

Copy link
Copy Markdown
Member

Closes #9 (concrete half; virtual servers are a follow-up spec). Ring Master job 2026-10-23-1917-virtual-and-concrete-mcp-servers.

Goal

Rename the McpServer domain to ConcreteServer without breaking host servers, models, policy config or stored data, and let Cortex override the tool list of a concrete (class-based) server the way it already overrides its instructions.

What's in it

  • Rename: src/Domains/McpServer → src/Domains/ConcreteServer. Table keys, routes, MCP tool names, config keys and server names unchanged.
  • Compatibility: lazy class-name shims for Support\Server, HasVersionedInstructions, the two models and their policies (autoload fallback in shims.php, @deprecated); a moved to warning for unshimmed old names; morph aliases keeping the old FQCN as the stored morph string, with a boot check; cortex.policies entries keyed by old model FQCNs remapped with a deprecation warning.
  • Tool override: nullable json tools column on mcp_instructions (idempotent migration; missing column or a throwing check degrades to code tools with a rate-limited warning); UpdateConcreteServerToolsAction / ClearConcreteServerToolsAction behind a new updateTools ability; serving rebuilds the ServerContext with the stored list in stored order, once per request, falling back to code tools on failure; stale, failing, ambiguous and corrupt entries are skipped and warned about through a cache-backed WarningLimiter (cortex.mcp.warning_ttl).
  • Surfaces: PUT/DELETE cortex/servers/{server}/tools, MCP update-server-tools / clear-server-tools, resource fields tools, tools_overridden, missing_tools, ambiguous_tools; Atrium tool editor with "restore code tools". The cortex server stays non-overridable.
  • Delete semantics change: DELETE …/instructions now keeps a row that still holds a tool override (answers 200 with the resource then; 204 / text when the row is removed, D-057). One Keen audit entry per delete (D-056).
  • Guest boot warning while updateTools is open to guests; README, CHANGELOG, config banners and the Boost skill updated.
  • CI: refactor-circus/keen in require-dev, composer dump-autoload before the tests, a guard that Keen tests do not skip in CI.

Acceptance criteria → tests

AC Tests
1, 2 Compat/OldNamespaceReferencesTest, McpServerRegistryTest, Http/McpInstructionsTest, Mcp/ServerInstructionToolsTest
3, 4, 5 Compat/MorphAliasesTest, Compat/KeenInCiTest
6 Compat/ClassShimsTest, tests/Fixtures/old-namespace-child.php
7 Compat/OldPolicyKeysTest
8 ToolsMigrationTest, McpToolOverridesTest
9, 9a ConcreteServerToolsActionsTest, ConcreteServerToolsRaceTest, Http/ConcreteServerToolsTest, Mcp/ServerToolsToolsTest, PolicyTest, GuestToolsWarningTest
10, 10a–10f Mcp/ServerToolOverrideTest, Mcp/ServerToolOverrideWarningsTest, Mcp/ServerContextPinTest, Compat/OldNamespaceToolOverrideTest
11 DeleteMcpInstructionActionTest, Http/McpInstructionsTest
12 McpServerRegistryTest, Unit/McpServerRegistryDefaultToolsTest, Ui/ServerToolsEditorTest
13 ConcreteServerToolsActionsTest, ConcreteServerToolsRaceTest
14 Http/ConcreteServerToolsTest, Mcp/ServerToolsToolsTest, Mcp/OutputSchemaTest
15 ToolOnlyRowTest, Http/ConcreteServerToolsTest
16, 18 Mcp/ServerToolOverrideWarningsTest, WarningLimiterTest, McpToolOverridesTest
17 ConcreteServerToolsCacheTest
19 Ui/ServerToolsEditorTest, Ui/StylesTest
20 Modes/RenamedTables/RenamedTablesTest
21 DocsTest
22 gate below

Gate (round 2): composer test green: phpstan 0 errors, pint, Pest 654 tests / 2499 assertions; ringside check passes. Review: 2 rounds, no nits left.

Before merging

  • Keystone (D-052): Keystone's CortexIntegration must look up the new Domains\ConcreteServer\Services\… classes. That change (b8e3477) is on Keystone branch ring-master/2026-10-23-1917-cortex-concrete-server-lookup, not on Keystone main. Merge it (and release it, if Cortex moves off dev-main) before this PR; CI here installs Keystone dev-main from VCS and will look up the old class names until then.
  • Atrium's SearchRegistry no longer uses unserialize (Atrium main), which cleared the local-only ArchTest failure (D-054, D-058).

🤖 Generated with Claude Code

…erver domain to ConcreteServer

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
jayjfletcher and others added 13 commits October 24, 2026 21:50
…shims

Lazy autoload fallback for the old Domains\McpServer prefix (src/Domains/ConcreteServer/shims.php, listed in autoload.files): aliases Support\Server, Concerns\HasVersionedInstructions, the two models and the two policies on request, and logs '<old> moved to <new>' for other old names. Also commits the group 9 composer.json edits (keen in require-dev, its VCS repository, dump-autoload first in the test script).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… remap

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…I checks

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…n, registry and tool-override storage

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…n, registry and tool-override storage

A throwing tools-column check reads as no tool override for that call
(D-055): McpToolOverrides warns through WarningLimiter (subject
column-check:<exception class>, context server and message) and nothing
is memoized, so the next call checks again.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ar and delete actions with policy and boot warning

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… overridden tool list

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…P surfaces and resource payload

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…P surfaces and resource payload

D-057: DELETE cortex/servers/{server}/instructions and
delete-server-instructions-tool answer 204/text when the override row is
removed, and 200 McpInstructionResource / structured content when the row
survives with its tool override.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… override editor

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…les, docs and quality gate

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
No code change: the ArchTest security-preset failure on the symlinked
Atrium is the local failure D-054 accepts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Regenerate the Ring Master block in AGENTS.md with ringside sync so the generated-files check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jayjfletcher jayjfletcher changed the title #9: Rename McpServer domain to ConcreteServer (concrete MCP servers, part 1) #9: Virtual and concrete MCP servers (concrete servers: rename and tool override) Oct 26, 2026
@jayjfletcher
jayjfletcher merged commit 06bc88d into main Oct 27, 2026
4 checks passed
@jayjfletcher
jayjfletcher deleted the ring-master/2026-10-23-1917-virtual-and-concrete-mcp-servers branch October 27, 2026 04:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Virtual and concrete MCP servers

1 participant